Add general partial_implementation guideline

[ddbeck]

Summary

This PR provides a general guideline for setting partial_implementation.

Related issues

This continues a discussion started in #26605 (comment).

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[ddbeck]

I suppose one thing that is potentially missing here—or at least not directly mentioned—is some notion of severity: how do we know to use a note alone versus note+partial? A good example of this being a concern is on something like Safari's top-level await bug (#26510) or css.properties.accent-color.maintains_contrast (#26605). This guideline basically says that severity is no matter; if it's inconsistent and difficult to detect as such, we flag it as partial.

My inclination is to adopt a guideline like this, which doesn't require a judgment call on severity, and wait to see if we find a situation where the guideline requires us to do something overtly silly.

[caugner]

LGTM so far, just one nit.

And one possible extension: What about BCD features with subfeatures? In general, we don't set partial_implementation: true on the parent feature, e.g. a CSS property, if the information can be captured on a subfeature, e.g. a CSS property value with partial_implementation: true or version_added: false.

[ddbeck]

And one possible extension: What about BCD features with subfeatures? In general, we don't set partial_implementation: true on the parent feature, e.g. a CSS property, if the information can be captured on a subfeature, e.g. a CSS property value with partial_implementation: true or version_added: false.

If you wish to make this explicit you can, though we don't really document (for example) promoting "version_added": false to parent features. Though a possible coda to this guideline might be:

Setting partial_implementation stands alone. Unlike "version_added": false, partial_implementation does not dictate support data to descendant features. Likewise, a subfeature's "version_added": false never justifies "version_added": false or "partial_implementation": true for an ancestor feature.

[caugner]

Though a possible coda to this guideline might be:

Setting partial_implementation stands alone. Unlike "version_added": false, partial_implementation does not dictate support data to descendant features. Likewise, a subfeature's "version_added": false never justifies "version_added": false or "partial_implementation": true for an ancestor feature.

Yes, please, I like that.

[caugner]

Some mostly structural suggestions to ease skimming, reading, and referencing:

[caugner]

Suggested change

	## `"partial_implementation"` general usage guidelines
	## When to use `"partial_implementation"`

[caugner]

Suggested change

	- The browser's support does not implement mandatory specified behavior.
	- The browser's support is inconsistent with at least one other browser.
	- The browser's support causes confusing feature detection results.
	1. The browser's support does not implement mandatory specified behavior.
	2. The browser's support is inconsistent with at least one other browser.
	3. The browser's support causes confusing feature detection results.

[ddbeck]

I don't think this is a good suggestion. This is not a sequence and there's no order.

[caugner]

(Admittedly, this is a rewording)

Suggested change

	Setting `partial_implementation` stands alone.
	Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features.
	Likewise, a subfeature's `"version_added": false` does not imply `"version_added": false` or `"partial_implementation": true` for an ancestor feature.
	Setting `partial_implementation` stands alone. This means:
	- If a subfeature covers the specified behavior, do **not** set `partial_implementation` on the parent feature. Set `"version_added": false` or `partial_implementation: true` on that subfeature instead.
	- If a subfeature has `"version_added": false` or `partial_implementation: true`, this does **not** imply `"partial_implementation": true` on the parent feature.

[ddbeck]

I originally added this text on your suggestion, noted in #26780 (comment). Now that I'm seeing your rewrite, I think this entire paragraph is a poor fit for this guideline. Instead, I think you should propose your own guideline to cover data bubbling/cascading.

Suggested change

	Setting `partial_implementation` stands alone.
	Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features.
	Likewise, a subfeature's `"version_added": false` does not imply `"version_added": false` or `"partial_implementation": true` for an ancestor feature.

[caugner]

(Admittedly, this is a rewording)

Suggested change

	Here are some example situations:
	- `"partial_implementation": false`: All implementing browsers ignore part of a feature's specified behavior in the same way.
	This behavior is consistent and is a _de facto_ complete implementation.
	- `"partial_implementation": false`: All implementing browsers provide a form control user interface, but the specification gives the implementer discretion over its look and feel.
	A developer complains that one browser's user interface lacks some desired quality that other browsers implement; they want it to be marked as partially implemented.
	Use a note or non-standard behavioral subfeature instead.
	**Don't set** `partial_implementation` when all implementing browsers …
	1. … ignore part of a feature's specified behavior in the same way
	(this consistent behavior constitutes a _de facto_ complete implementation), or
	2. … provide a form control user interface, but the specification gives the implementer discretion over its look and feel
	(if one browsers' user interface lacks some quality that is desired by developers, and that other browsers implement, create a non-standard behavioral subfeature instead).

[ddbeck]

I don't think this rewrite has the same intent as what I originally wrote. I provided some supplementary examples. I don't mean for themselves to be instructions (especially since it's not hard to come up with an example that mixes more than one scenario).

Additionally, this style of breaking a sentence with a list reads very poorly to me, like something a lawyer would write into terms and conditions. It certainly goes against every style guide I've worked under.

[caugner]

Suggested change

	- `"partial_implementation": true`: `CSS.supports()` returns `true` for a property name and value, but the value has no behavior.
	See [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation).
	- `"partial_implementation": true`: One browser exposes a constructor, `Example()`, but it always throws an error. Other browsers implement the constructor's intended behavior. This confuses feature detection because `typeof Example === "function"` returns `true`, even though the constructor does not work.
	Set `partial_implementation: true` in these cases:
	- `CSS.supports()` returns `true` for a property name and value, but the value has no behavior in this browser, and the value has the intended behavior in another browser.
	_See also_: [Non-functional defined names imply `"partial_implementation"`](#non-functional-defined-names-imply-partial_implementation).
	- The browser exposes a constructor, `Example()`, but it always throws an error, and another browser implements the constructor's intended behavior.
	_Note_: This confuses feature detection because `typeof Example === "function"` returns `true`, even though the constructor does not work.

[ddbeck]

See my comment on the previous suggestion. I don't think we should convert these examples into instructions because it makes it appear as if the examples are comprehensive rules. They are not.

[pygy]

As mentioned in #26838 (comment), I think that point 1...

1. The browser's support does not implement mandatory specified behavior.

... should be sufficient to mark support as partial if the missing behavior pertains to accessibility, especially if the lack of support isn't obvious to the layman as the feature seems to work.

Alternatively, it would be nice to be able to prominently warn of accessibility pitfalls, even if it isn't through the partial_implementation field.

[ddbeck]

@pygy For context, this PR is meant to regularize a process we already do here, so I don't think introducing new criteria is in scope. But for completeness, I'll say that I don't believe that deviation from a specification alone is a workable trigger for partial_implementation. Specifications evolve well ahead of implementations, often in highly speculative ways that no vendor has committed to implementing. If we relied solely on spec compliance then many interoperable features would need to be marked as partially implemented despite having no meaningful compatibility risks to developers.

There is a concurrent proposal, #26781, to regularize "behavioral subfeatures" which typically capture the kind of relatively anonymous specification evolution that has gone on for #26838.

That said, nothing in this PR (or the behavioral subfeature PR) should be understood to forbid (non-partial) notes about bugs and other limitations, accessibility or otherwise.

[captainbrosset]

What if it's the other browser that's wrong?

[caugner]

I think what's meant here is:

At least one other browser implements this behavior.

[captainbrosset]

Ok. In that case, I'd suggest rephrasing.
Right now, this reads as "set partial implementation to true if this browser doesn't work like that other browser". And to me, I have no way of know which browser is right.

[hamishwillee]

@caugner (as you know and have commented) Given an interface, it is not uncommon for new properties or methods to be added later. At that point the parent interface becomes partial even if it was complete previously. My understanding though is that you wouldn't "go back" and capture that in the interface level. The interface would remain complete?

[chrisdavidmills]

My understanding of "complete" would be "complete at the time the data was written", so it would still hold true if another feature was added later. Does that need clarifying? It would be a real mess if people started going around retroactively marking data as partial because new features were added later.

[ddbeck]

To answer some questions here:

Right now, this reads as "set partial implementation to true if this browser doesn't work like that other browser". And to me, I have no way of know which browser is right.

All three conditions must be met. The spec is almost always right—unless all implementers ignore the spec same exact way. It's possible to have partials for all implementers, if they all differ from the spec and they're not all mutually compatible.

At that point the parent interface becomes partial even if it was complete previously. My understanding though is that you wouldn't "go back" and capture that in the interface level. The interface would remain complete?

Partial data doesn't cascade to descendants and it doesn't bubble up to parents. Intl is probably the idealized case: Intl is fully supported ever since it was exposed because being exposed is all it does. The fact that Intl.Segmenter was added much later doesn't matter for Intl—we don't retroactively mark it as partial.

I'm not trying to propose any radical changes here. Instead, I'm trying to describe what we usually do most of the time anyway.

[ddbeck]

Some responses to @caugner's writing suggestions.

[ddbeck]

I don't think this is a good suggestion. This is not a sequence and there's no order.

[ddbeck]

I originally added this text on your suggestion, noted in #26780 (comment). Now that I'm seeing your rewrite, I think this entire paragraph is a poor fit for this guideline. Instead, I think you should propose your own guideline to cover data bubbling/cascading.

Suggested change

	Setting `partial_implementation` stands alone.
	Unlike `"version_added": false`, `partial_implementation` does not dictate support data to descendant features.
	Likewise, a subfeature's `"version_added": false` does not imply `"version_added": false` or `"partial_implementation": true` for an ancestor feature.

[ddbeck]

I don't think this rewrite has the same intent as what I originally wrote. I provided some supplementary examples. I don't mean for themselves to be instructions (especially since it's not hard to come up with an example that mixes more than one scenario).

Additionally, this style of breaking a sentence with a list reads very poorly to me, like something a lawyer would write into terms and conditions. It certainly goes against every style guide I've worked under.

[ddbeck]

See my comment on the previous suggestion. I don't think we should convert these examples into instructions because it makes it appear as if the examples are comprehensive rules. They are not.